Nebula 1

home *** CD-ROM | disk | FTP | other *** search

/ Nebula 1 / Nebula One.iso / Internet / WWW / Perl_WWW_Utilities / MHonArc / doc / mhonarc.txt < prev next >

Wrap

Text File | 1996-04-18 | 130.8 KB | 4,594 lines

MHONARC An Internet mail-to-HTML converter. _________________________________________________________________ Table of Contents * Introduction + Why Use MHonArc? + Supported Platforms + Availability + About the Documentation * Installation + System Requirements + Extracting the Distribution File + Installing the Software + Tested Environments * Quick Start + Converting MH mail folders or Mailbox files + Adding Messages to an Archive + Converting a single message * Overview + Synopsis + Options + Environment * Resource File + Resource Syntax + Resource Elements + Example Resource File + Notes on Resource File * Adding Messages + Examples * Removing Messages + Message Numbers + Scanning an Archive * Index Page Customization + Filename + Beginning Markup + End Markup + Include Files + Listing Layout + Icons + Examples * Thread Index Customization + Filename + Beginning Markup + End Markup + Listing Layout * Message Customization + Beginning Markup + End Markup + Header and Footer + Navigational Links + Message Layout + Other Resources * MIME + Default Filters + Non-MIME Messages + Writing Filters + Specifying Filters * Gory Details + OS Detection + Processing Steps + Archive Integrity + File Formats + Notes * Diagnostics + Informative messages + Warnings + Errors + Perl Messages * Glossary * Contacts + Mailing List + People _________________________________________________________________ Earl Hood <ehood@convex.hp.com> Hewlett-Packard Convex 3000 Waterview Parkway P.O. Box 833851 Richardson, TX 75083-3851 Phone: (214) 497-4387 FAX: (214) 497-4500 _________________________________________________________________ _________________________________________________________________ INTRODUCTION MHonArc is a Perl program for converting e-mail messages as specified in RFC 822 and RFC 1521 (MIME) to HTML. MHonArc can perform the following tasks: * Convert mh(1) mail folders or UUCP/Unix style mailboxes into an HTML mail archive. * Add or remove messages to an existing HTML mail archive generated by MHonArc. * Convert a single message to HTML. Along with these tasks, MHonArc provides the following: * A main customizable index page for mail messages archived. * A customizable thread index page listing messages by thread. * Control over message formatting. * The ability to hook in your own custom message filters. _________________________________________________________________ Why Use MHonArc? Here are some reasons for using MHonArc: * You want to keep organized archives of mail messages and/or news articles for a World Wide Web (WWW) server; complete with live hypertext pointers to their authors and to any url's mentioned. * You would like to control the layout of mail/news archives to keep a consistent style to your WWW pages. * You have a WWW client, but no MIME mail reader. MHonArc will allow you to read MIME messages that includes images, audio, video, etc via your Web client. * Muli-platform support: MS-DOS and Unix. * You think the MHonArc logo is really cool, and it deserves to be used. * You like Perl, and you want to see what it can do. * Just cuz. _________________________________________________________________ Supported Platforms MHonArc (version 1.1, or later) will run under Unix or MS-DOS operating systems with Perl 4 or 5 installed. _________________________________________________________________ Availability The latest information on MHonArc, and its availability, may be obtained at <URL:http://www.oac.uci.edu/indiv/ehood/mhonarc.html>. _________________________________________________________________ About the Documentation The documentation is oriented towards Unix users. However, the section on Installation does conver MS-DOS installation instructions. Notes are made in the documentation when something may differ due to the operating system. _________________________________________________________________ _________________________________________________________________ INSTALLATION This section instructs you on how to install and get MHonArc running on your machine. The section covers Unix installation and MS-DOS/Windows installation. NOTE For brevity, anything that applies to MS-DOS also applies to Windows. _________________________________________________________________ System Requirements MHonArc is written in Perl 4. Therefore, you must have Perl 4 or 5 installed on your system. If you do not know if Perl is installed on your system, ask your system administrator. If Perl is not installed on your system, you can retrieve Perl at <URL:http://www.cis.ufl.edu/perl/ftp.html>. I recommend version 4.0 patchlevel 34, or later. MHonArc has not been tested on earlier versions. NOTE MHonArc makes use of the Perl libraries newgetopt.pl and timelocal.pl. These libraries are part of the normal Perl distribution. _________________________________________________________________ Extracting the Distribution File Before extracting the distribution file, you may want copy the distribution file into scratch directory, and work in there during installation. TAR/GZIP DISTRIBUTION You must have gzip and tar installed on your system. If gzip is not installed, you may obtain gzip at <URL:ftp://prep.ai.mit.edu/pub/gnu>. Tar comes with all Unix systems. However, MS-DOS users may have to obtain tar. To extract the file, type the following command at your shell's prompt: Unix zcat MHonArc.tar.gz | tar xvof - MS-DOS gunzip -dv MHonArc.tar.gz tar xvf MHonArc.tar A directory called "MHonArc" should be created. The directory contains all the files need for installing MHonArc. NOTE The actual name of the distribution file may differ from the example given. ZIP DISTRIBUTION You must have pkzip or unzip installed on your system. To extract the file, type the following command at your shell's prompt: unzip mhonarc.zip OR pkunzip -d mhonarc.zip IMPORTANT The directory structure of the zip file must be preserved during extraction to insure proper installation. A directory called "MHonArc" should be created. The directory contains all the files need for installing MHonArc. NOTE The actual name of the distribution file may differ from the example given. _________________________________________________________________ Installing the Software Once you have extracted the distribution file, change your current working directory into the MHonArc directory created during the extraction of the distribution file. Example: Assuming you are in the directory you extracted the distribution file in, you can type the following on your command-line: Unix cd MHonArc MS-DOS cd MHONARC INSTALL.ME Contained in the MHonArc directory is a Perl program called "install.me". This program will perform the tasks required to install MHonArc on you machine. The install program is capable of running interactively, or in batch. Interactive Mode To run install.me in interactive mode, type the following at your shell's prompt: perl install.me NOTE Make sure you are in the same directory as the install.me program. The program will then prompt you for the necessary information to install MHonArc on your system. Here's an example (Unix) session: % perl install.me MHonArc Installation ==================== The installation process will ask you a series of questions on where the Perl executable is and where to put MHonArc files. Just hit <CR> to accept the default values listed in ()'s. If directory path does not exist on your system, the installation program will create the path for you. ----------------------------------------------- Note: Make sure all pathnames are absolute. ----------------------------------------------- Hit <CR> to continue ... Perl executable ("/usr/local/bin/perl") -> /usr/bin/perl Location to install programs ("/usr/local/bin") -> /mnt/ehood/bin Location to install libraries ("/usr/local/lib/MHonArc") -> /mnt/ehood/lib/MHonArc Install documentation ("y")? y Location to install docs ("/usr/local/lib/MHonArc/doc") -> /mnt/ehood/lib/MHonArc/doc You've specified the following: Perl location: /usr/bin/perl Program directory: /mnt/ehood/bin Library directory: /mnt/ehood/lib/MHonArc Doc directory: /mnt/ehood/lib/MHonArc/doc Is this correct ("y")? y Installing the following into /mnt/ehood/bin mhonarc Installing the following into /mnt/ehood/lib/MHonArc base64.pl mhexternal.pl mhtxthtml.pl mhtxtplain.pl mhtxtsetext.pl qprint.pl readmail.pl Installing the following into /mnt/ehood/lib/MHonArc/doc mhonarc.txt ... Batch Mode To run install.me in batch mode, type the following at your shell's prompt: perl install.me install.cfg NOTE Make sure you are in the same directory as the install.me program. The install.cfg contains the necessary information for intalling MHonArc on your system. You will need to edit install.cfg to reflect your installation requirements. Here is an example install.cfg: # Should executables be installed. 0 => NO, non-zero => YES. # $dobin = 1; # Should libraries be installed. 0 => NO, non-zero => YES. # $dolib = 1; # Should documentation be installed. 0 => NO, non-zero => YES. # $dodoc = 1; # Location for executable. If using ms-dos, use something like # 'C:\\BIN'. # $bindir = '/usr/local/bin'; # Location for libraries. If using ms-dos, use something like # 'C:\\LIB\\MHONARC'. # $libdir = '/usr/local/lib/MHonArc'; # Location for documents. If using ms-dos, use something like # 'C:\\DOC\\MHONARC'. # $docdir = '/usr/local/lib/MHonArc/doc'; # Location of perl executable. If using ms-dos, use something like # 'C:\\BIN\\PERL.EXE'. # $perlprg = '/usr/local/bin/perl'; 1; # DO NOT DELETE THIS LINE The file is Perl code, and therefore, must follow Perl syntax rules: * Anything following a `#' character is ignored. * Strings values need to be enclosed in quotes. * If you need to use a backslash in a string value, it must be escaped with a backslash. Example: 'C:\\LIB\\MHONARC'. The same applies to the '$' character. * All statements must end with a semi-colon. * The "1;" line must not be deleted. NOTE You can verify the syntax of the configuration file by invoking "perl -c" on the file. After you have successfully executed install.me, MHonArc is ready to use. MS-DOS Post install.me Note If you would like the ability to run MHonArc like other programs, then create a batch file that contains something like the following: @ECHO OFF C:\BIN\PERL.EXE C:\BIN\MHONARC %1 %2 %3 %4 %5 %6 %7 %8 %9 Of course, you will need to change the paths to Perl and MHonArc to suit your systems configuration. Sample batch files are available in the MHonArc distribution. NOTES ON INSTALL.ME * If you do not know the location of the Perl executable on your system, ask your system administrator. * All pathnames must be absolute. * If a path does not exist that you specify, the path will be automatically created if running in interactive mode. In batch mode, all paths specified must already exist. * During the installation process, the main MHonArc source file is modified to be aware of the location of the Perl executable and MHonArc's library files. If you ever need to install MHonArc in a different location, rerun the install.me program. NOTE: Location of the Perl exectuble is only relevant for Unix systems. MS-DOS systems do not make use of the "#!" line in scripts. * MHonArc requires the use of timelocal.pl and newgetopt.pl. These libraries are part of the normal Perl distribution. _________________________________________________________________ Tested Environments This section covers software environments MHonArc has worked successfully. Feedback is welcome about other success, or failure, stories covering MHonArc usage in other environments. PERL MHonArc is known to work with the following version of Perl 4, or later: $RCSfile: perl.c,v $$Revision: 4.0.1.7 $$Date: 92/06/08 14:50:39 $ Patch level: 34 MHonArc is known also to work with Perl 5.001m and Perl 5.002 beta2. NOTE The version numbers are based upon the Unix versions of Perl. DOS version numbers may differ. UNIX Mail Software * MH * Elm, Mail, mail, and any other mail software that stores e-mail in UUCP style mailbox format. UUCP format is where mail messages are separated by a line beginning with "From " (I.e. the word "From" followed by a space). You may need to utilize the MSGSEP resource if the message separator is different from standard mailbox files (eg. MMDF format). News Software Different news software store messages differently. Messages are either stored in a format similiar to MH or similiar to a mailbox file: * MH style is where the messages are stored in a directory with each post a separate file, and each file has a numeric filename. * Mailbox style is where messages are stored in a single file. You may need to utilize the MSGSEP resource if the message separator is different from standard mailbox files. MS-DOS Mail/News Software MHonArc has been tested under MS-DOS with message files created by the following mail and news programs: * Eudora * WinVN * Windows Trumpet * NUPop It also works with individual RFC822 mail messages, but you must run MHonArc without a batch file if you need to use redirection. For example: perl c:\bin\mhonarc <one.msg >one.htm perl c:\bin\mhonarc -add <one.msg _________________________________________________________________ _________________________________________________________________ QUICK START This section will give you a "quick start" on using MHonArc. However, I recommend reading through the entire documentation to take full advantage of all the features of MHonArc. Before continuing, make sure MHonArc has been installed. See Installation if MHonArc has not been installed on your machine. _________________________________________________________________ Converting MH mail folders or Mailbox files Since MHonArc supports MH mail folders and UUCP/Unix mailbox files, the term "mail folder" will represent the MH mail folder or mailbox file you want to process. To convert your mail folder to an HTML archive, use the following: % mhonarc <path>/inbox Where <path> represents the path to the directory that contains the mail folder inbox. If you are in the directory that contains inbox, then you can leave out the "<path>/". MHonArc prints out messages showing its progress as your e-mail is processed. When MHonArc finishes, the following files will be created: * maillist.html: The main index file containing links to all mail messages converted. Messages are listed with subjects and who the messages are from. All messages are listed in sorted order by date received/sent. * threads.html: The file listing messages by thread. * msg*.html: HTML versions of the mail messages, where * represents a message number from 0 to the number of message processed minus 1. * .mhonarc.db (or MHONARC.DB under MS-DOS): This database file is needed inorder for MHonArc to perform additions of new mail messages to the archive. Information is stored to perform mail threading updates when new messages are added, as well as any resources set via Environment variables, Resource File, and/or command-line Options. * Other: Depending on the content-types of the e-mail messages converted, other files may be created for images, videos, binaries, etc. See the section on MIME for more information. The format of each converted mail message is as follows: * A <LINK REV="made" HREF="mailto:from_address"> is inserted in the HEAD element of HTML mail message file. This allows readers of the message to send comments to the author of the mail message within Web browsers that support such functionality (like Lynx). * The title (i.e. TITLE element) contains the subject of the message. * Hyperlinks to the previous and next messages and the index pages are located at the top of the message. * Next, the subject appears in a H1 element. * Next, follows the mail header with fields listed in a UL element surrounded by HR's. * Next, the actual body of the mail message. * Next, links to any follow-up, or referenced, messages. The messages are listed by subject and who they are from. These links allows you to easily follow mail threads. * Last, are verbose links to the previous mail message, next mail message, and index pages. The following is also done for each mail message processed: * Links are created in the "References" and "In-Reply-To" header fields, and possibly the message body, if the destination message-ids are being processed. * E-mail addresses are converted to "mailto" hyperlinks in "To:", "From:", "Cc:", and "Sender:" mail header fields. Currently, not all Web browsers support the mailto URL. * Newsgroups listed in a "Newsgroups:" mail header field are converted to news hyperlinks. MHonArc allows you to specify more than one mail folder to process on the command-line. Example % mhonarc /home/ehood/mail/inbox1 /home/ehood/mail/inbox2 ... All the files created will be put into the current working directory, by default. You can control the destination of the output location by using the -outdir option. Example % mhonarc -outdir /home/ehood/htmlarchive /home/ehood/mail/inbox Here is a sample session converting a mail folder: % mhonarc ~/mail/inbox Requiring MIME filter libraries ... mhexternal.pl mhtxthtml.pl mhtxtplain.pl mhtxtsetext.pl Converting messages to ./maillist.html Reading /mnt/ehood/mail/inbox .......... Writing mail ... Writing tmp/maillist.html ... Writing tmp/threads.html ... 10 messages _________________________________________________________________ Adding Messages to an Archive If you have new messages you want to add to an existing archive, you must utilizing the -add command-line option. With the -add, you can do the following: * Add a mail folder to an archive, or * Add a single message to an archive. Adding a mail folder to an archive in the current working directory can be done like the following: % mhonarc -add <path>/mailfolder If you are not in the same directory as the archive, then you can specify the location of the archive to add to with the -outdir option: % mhonarc -add -outdir <outdir_path> <path>/mailfolder NOTE MHonArc will skip any messages that already exist in the archive. Therefore, MHonArc can be used to rescan the same mail folder and only convert any new messages it finds. If no mail folder arguments are specified, then MHonArc will attempt to add a single message read in from standard input. Example % mhonarc -add < single.msg Or, from a pipe: % cat single.msg | mhonarc -add See the section on Adding Messages for more information and examples for adding messages to an archive. _________________________________________________________________ Converting a single message MHonArc has the ability to process a single mail message independent of creating, or modifying, and archive. To convert a single message to HTML use the -single command-line option. The message to process can be specified by a filename on the command-line, or by reading the message from standard input if no file is specified. The filtered message is sent to standard output. All formatting options apply to the single message as with messages being processed for an archive, with the exception of formatting related specificly to archive processing, like index links and mail thread links. EXAMPLES Input from standard input: % mhonarc -single < messagefile > file.html Filename on command-line: % mhonarc -single messagefile > file.html _________________________________________________________________ _________________________________________________________________ OVERVIEW This section gives an overview of MHonArc's command-line options and environment variables. The MHonArc resource file is covered in the section Resource File. The resource file allows you to specify most of the resources set by environment variables and command-line options, plus it give you the capability of completely customizing the HTML output generated by MHonArc. _________________________________________________________________ Synopsis Invoke MHonArc from your shell with the following syntax: % mhonarc [options] mhfolder... % mhonarc [options] mailbox ... % mhonarc -add [options] < message % mhonarc -single [options] < message > message.html % mhonarc -single [options] message > message.html % mhonarc -rmm [options] msg# ... _________________________________________________________________ Options The following options are available: -ADD Add new messages to an existing archive. If no mail folder arguments are given, MHonArc assumes that a single message is being added to the archive via standard input. Otherwise, MHonArc adds the messages contained in the mail folders specified. -DBFILE NAME Use name for the name of MHonArc database file. The default is ".mhonarc.db" (or "MHONARC.DB" under MS-DOS). NOTE You should not override the default name unless absolutely necessary, and you are confident about what you are doing. -DOCURL URL Use url as the URL to MHonArc documentation. The default is "http://www.oac.uci.edu/indiv/ehood/mhonarc.html". -EDITIDX This option tells MHonArc to rewrite the index page and re-edit all mail messages in the archive. This option is useful if you need to change the layout of the index page and/or messages. -FOOTER FILENAME Insert contents of filename at the bottom of the index page. See Include Files in Index Page Customization for more information about the footer file. -FORCE Override a lock on an archive if attempts to lock fail. I.e. After trying unsuccessfully to lock an archive, MHonArc will still perform the actions requested. This option is useful to help dealing with locks that are no longer valid (i.e. stale locks). A stale lock can exist if the MHonArc process that created the lock abnormally terminated and could not perform the proper cleanup procedures. -GENIDX Output an index page to standard output based upon the contents of an archive, and utilizing any extra formatting options specified. -HEADER FILENAME Insert contents of filename at the beginning of the index page. See Include Files in Index Page Customization for more information about the header file. -HELP Print out a help message about MHonArc. -IDXFNAME NAME Sets the name of the main index file to name. The default is "maillist.html". -IDXSIZE # Set the maximum number of messages listed in the indexes. -LOCKDELAY # The sleep time, in seconds, between attempts to lock the archive. The default value is 3. -LOCKTRIES # Set the number of time MHonArc tries to lock a mail archive before processing new messages. The default value is 10. MHonArc waits approximately 3 seconds before each try. See Archive Integrity for more information on the -locktries options. -MAILTOURL URL Use url for e-mail address hyperlinks in mail message headers. The url can contain the following variables that get expanded during run-time: $FROM$ Who the message is from. $MSGID$ Message ID of the message. $SUBJECT$ The subject of the message. $TO$ Destination e-mail address of link. The default URL is "mailto:$TO$" The -mailtourl option has no effect if the -nomailto option is specified. -MAXSIZE # Set the maxinum number of messages allowed in the archive to #. If messages are added to the archive which would cause the total number of messages to exceed #, older messages (based on sort method) are removed automatically. -MSGSEP EXPRESSION Use the expression as the Perl regular expression that signifies the message separator in Unix mailbox files. The default expression is "^From " (minus the quotes). NOTE There is a space character after the From. -NODOC Do not print link to documentation at end of index page. -NOMAILTO Do not convert e-mail addresses in mail headers to mailto hyperlinks. -NONEWS Do not convert newsgroups in the Newsgroups: mail header field to news hyperlinks. -NOREVERSE Do not perform a reverse listing of the mail messages in the index page. -NOSORT Do not sort messages by date. Messages will be in the order they appear in the mailboxes/folders. By default, MHonArc sorts messages by date sent/received. -nosort takes precedence over the -sort option. -NOTHREAD Do not create a thread index page. -NOTSUBSORT Do not sort threads by subject on thread index page. -NOTREVERSE List threads in the thread index with oldest thread first. -OUTDIR PATH Set destination/location of the HTML mail archive to path. By default, the current working directory is used. -QUIET Suppress processing messages when MHonArc is running. -RCFILE FILE Use file as the resource file for MHonArc. MHonArc does the following to determine the location of file: 1. If its an absolute pathname, use it. 2. If it is a relative pathname, check for it relative to the current working directory. 3. Otherwise, check for it relative to the location of the archive. See Resource File for more information. There is no default resource file. -REVERSE List messages in reverse order of the sorting option specified. For example, if date sorting is specified, -reverse will cause messages to be listed in reverse chronological order. -RMM All non-option command-line arguments are treated as messages to remove from the archive. Messages to remove are denoted by their message numbers. -SAVEMEM Normally, all messages are stored in memory and then written in one shot. This option causes MHonArc to write the message data as it is processesd. This option will cause a slow down in execution time as more disk I/O required, but it may allow large amounts of data to be processed in a single process if memory is limited. NOTE The reason more disk I/O is required is that when the message data is first written, all the archive navigational link information is non-existant. The information required to correctly generate the navigational link information will not exist until all messages are processed. Therefore, each new message file must be reopened to add in the navigational link information after all messages are processed. -SCAN List contents of archive to standard output. -SINGLE Convert a single mail message to HTML. The message can be specified by a filename on the command-line, or read from standard input if no file is given. The filtered message is sent to standard output. The -single option is useful tp convert individual messages to HTML not related to a specific mail archive. Any option related to how message formatting can be used with the -single option. The -single takes precedence over the -add option. -SORT Perform chronological date sorting. This is the default. -SUBSORT Sort messages by subject. Subject sorting is case-insensitive, and begining "Re:", "A", "An", and "The" words are ignored. -TIDXFNAME NAME Sets the name of the thread index file to name. The default is "threads.html". -TIME Print out total CPU execution time taken when processing messages. Time information is written to standard error. -TITLE STRING Set the title of the main index page to string. The default is "Mail Index". -THREAD Create a thread index page. This is the default. -TLEVELS Set the maximum number of nested lists for the thread index page. The default is 3. -TREVERSE List threads in the thread index with newest thread first. -TSUBSORT List threads in the thread index by subject. -TTITLE STRING Set the title of the thread index page to string. The default is "Mail Thread Index". -UMASK UMASK Set the umask of the MHonArc process to umask. The value is treated as an octal number. NOTE The -no* options always take precedence over their counterparts. For example, if -noreverse and -reverse are both specified on the command-line, the -noreverse will be applied. _________________________________________________________________ Environment MHonArc supports the use of environment variables. The environment variables allow you to set default options everytime you invoke MHonArc. The following environment variables may be used: M2H_DBFILE Sets the name of MHonArc database file. The default is ".mhonarc.db" (or "MHONARC.DB" under MS-DOS). NOTE You should not override the default name unless absolutely necessary, and you are confident about what you are doing. M2H_DOCURL Set the URL used to point to MHonArc documentation. The default is, "http://www.oac.uci.edu/indiv/ehood/mhonarc.html". M2H_FOOTER Set the HTML footer file to insert at the bottom of the index page. No default footer file is defined. See Include Files in Index Page Customization for more information about the footer file. M2H_HEADER Set the HTML header file to insert at the top of the index page. No default header file is defined. See Include Files in Index Page Customization for more information about the header file. M2H_IDXFNAME Set the name of the index file. The default is, "maillist.html". M2H_IDXSIZE Sets the maximum number of messages listed in the indexes. M2H_LOCKFILE The sleep time, in seconds, between attempts to lock the archive. The default value is 3. M2H_LOCKFILE Set the name of the lock file. The default name use is ".mhonarc.lck" (or "MHONARC.LCK" under MS-DOS). NOTE You should not change the default unless absolutely necessary. See Archive Integrity for more information about the lock file. M2H_LOCKTRIES Set the number of time MHonArc tries to lock a mail archive before processing new messages. The default value is 10. MHonArc waits approximately 3 seconds before each try. See Archive Integrity for more information on the M2H_LOCKTRIES environment variable. M2H_MAILTOURL Sets the URL for e-mail address hyperlinks in mail message headers. The URL can contain the following variables that get expanded during run-time: $FROM$ Who the message is from. $MSGID$ Message ID of the message. $SUBJECT$ The subject of the message. $TO$ Destination e-mail address of link. The default URL is "mailto:$TO$" M2H_MAXSIZE Sets the maximum number of messages that an archive will contain. If messages are added to the archive which would cause the total number of messages to exceed M2H_MAXSIZE, older messages (based on sort method) are removed automatically. M2H_OUTDIR Sets the destination/location of the HTML mail archive. The default is the current working directory. M2H_RCFILE Specifies the Resource File for MHonArc. No default resource file is defined. M2H_THREAD Flag to determine if MHonArc generates a thread index. If set to zero, the thread index will not be created. The default behavior is to create a thread index. M2H_TIDXFNAME Sets the name of the thread index file. The default is "threads.html". M2H_TITLE Sets the default title of the index page. The default is "Main Index". M2H_TLEVELS Sets the maximum number of nested lists for the thread index page. The default is 3. M2H_TTITLE Sets the title of the thread index page. The default is "Mail Thread Index". NOTE Environment variables may be overriden by the Resource File or command-line Options. _________________________________________________________________ _________________________________________________________________ RESOURCE FILE MHonArc supports the ability to read in a resource file to control the behavior of MHonArc. The resource file allows you to specify most of the resources set by environment variables and command-line options, and it allows you to specify other resources to control MHonArc's behavior. The resource file is specified by the M2H_RCFILE environment variable or the -rcfile command-line option. The command-line option overrides the environment variable if both are defined. NOTE MHonArc will store the information specified in the resource file in the database for the archive. Therefore, it is unnecessary to respecify the resource file duing archive updates unless changes are required from the current settings. _________________________________________________________________ Resource Syntax Resources are set in the file by using elements similiar in style to HTML/SGML markup. However, MHonArc uses simpler parsing rules for the resource file than standard SGML: * Any line that is not a recognized element open tag, and the line is not contained within an element, is ignored. This implies that regular text can be put anywhere outside of recognized elements for commenting purposes. NOTE: You should use SGML comment declarations () when commenting a resource file. This will eliminate possible conflict with later versions of MHonArc if more stricter parsing rules are adopted. * The opening tag of an element must occur by itself on a single line. Whitespace is allowed before the the open tag. * No comments are allowed inside elements because the text will be treated as element content. * Each element must be closed with a </element_name> tag on its own line unless explicitly stated otherwise in the Resource Elements section. Whitespace is allowed before the close tag. * Some elements can take an optional attribute called "Override". This tells MHonArc that the contents of the element will completely override the default behavior of MHonArc, and previous instances of the element. Example: "<EXCS Override>". If "Override" is not specified, then the contents of the element augment the current setting. * Element names are case-insensitive. * Elements can occur in any order in the resource file. RESOURCE VARIABLES Some resource element contents may contain variables. Variables get expanded to strings at run-time. NOTE Variable expansion will only take place in resource elements that are intended to have variables as part of their content. If an element is not meant to have variables, the variable text will be taken literally as part of the element content. The syntax of the variables to use in resource elements is as follows: $VARIABLE[:[N][U]]$ The items in []'s are optional. Definition of each part: $ The $ character represents the beginning, and ending, of the variable. VARIABLE This is the the actual name of the variable. All variable names must be uppercase. :[N][U] (optional) This defines a maximum length of the replacement string for the variable. The option "U" denotes that the replacement string should be treated as part of a URL string. This can be useful when the variable may contain special characters, and the variable is used withing a URL. No whitespace is allowed between the opening $ and closing $. If an unrecognized variable is encountered, it gets replaced with an empty string. If a literal "$" is needed, use "$$". SPECIAL NOTE The MAILTOURL resource has different rules for variable expansion. If a variable does not exactly match the set of variables available for the MAILTOURL, the variable text will be taken literally as part of the element content. Therefore, a single "$" can be used to represent a "$" character. Also, variables in the MAILTOURL should NOT have ":NU" modifier. This will prevent the variables from be recognized. MHonArc will automatically treat the replacement value as a part of a URL string. Here are some examples of legal variable usage: * $SUBJECT$ * $FROMNAME$ * $SUBJECT:50$ * $SUBJECTNA:60U$ * $FROMADDR:U$ Each resource element will define what variables are defined for it. _________________________________________________________________ Resource Elements The following are complete listings of all the resource elements defined by MHonArc. Many element descriptions will reference to other sections of the documentation on the exact usage of the element. EMPTY ELEMENTS The following list of elements contain no textual content. Therefore, no end tag is required: NODOC Do not put link to documentation on main index page. NOMAILTO Do not convert e-mail addresses in mail headers to mailto hyperlinks. NONEWS Do not convert newsgroups in the Newsgroups: mail header field to news hyperlinks. NOREVERSE Do not perform a reverse listing of the mail messages in the main index page. NOSORT List messages in the index page in the order they are processed. NOTHREAD Do not create thread index. NOTREVERSE List threads in the thread index with oldest thread first. NOTSUBSORT Do not sort thread by subject in thread index page. REVERSE List messages in reverse listing order for the main index page. SORT List messages in the index page in chronological order. SUBSORT Sort messages by subject. Subject sorting is case-insensitive, and begining "Re:", "A", "An", and "The" words are ignored. THREAD Create thread index. This is the default. TREVERSE List threads in the thread index with newest thread first. TSUBSORT Sort thread by subject in thread index page. NON-EMPTY ELEMENTS The following list of elements contain textual content, therefore, each element must be explicitly closed with an element end tag (examples are given in Example Resource File): BOTLINKS Markup for defining the various hyperlinks at the bottom of converted messages. See Navigational Links of Message Customization for usage of this element. DBFILE Use name for the name of MHonArc database file. The default is ".mhonarc.db" (or "MHONARC.DB" under MS-DOS). NOTE You should not override the default name unless absolutely necessary, and you are confident about what you are doing. DOCURL URL to MHonArc documentation. The default is "http://www.oac.uci.edu/indiv/ehood/mhonarc.html". EXCS Set of message header fields to exclude from messages. See Excluding Fields of Message Customization for usage of this element. FIELDORDER The order the message header fields appear in messages. See Field Order of Message Customization for usage of this element. FIELDSTYLES The format specification for message header field values. See Field Formatting of Message Customization for usage of this element. FOOTER File to include at the end of the index page. See Include Files in Index Page Customization for more information about the footer file. HEADER File to include at the beginning of the index page. See Include Files in Index Page Customization for more information about the header file. ICONS The ICONS element is used to specify the icons that represent the different content-types of messages. See Icons in Index Page Customization for usage of this element. IDXFNAME The name of the index file. The default is "maillist.html". LABELSTYLES The format specification for message header field labels. See Field Formatting in Message Customization for usage of this element. LISTBEGIN Markup for beginning the main index list. See Listing Layout in Index Page Customization for usage of this element. LITEMPLATE Markup for an entry in the main index list. See Listing Layout in Index Page Customization for usage of this element. LISTEND Markup for terminating the main index list. See Listing Layout in Index Page Customization for usage of this element. MAILTOURL Url to use for e-mail hyperlinks. See E-mail Links in Message Customization for usage of this element. MIMEARGS Arguments to MIME filters. See Specifying Filters in MIME for usage of this element. MIMEFILTERS Routines for filtering messages. See Specifying Filters in MIME for usage of this element. MSGFOOT Footer text for converted messages. See Header and Footer in Message Customization for usage of this element. MSGHEAD Header text for converted messages. See Header and Footer in Message Customization for usage of this element. MSGSEP Perl regular expression that represents the message separator for mailbox files. The default expression is "^From ". OTHERINDEXES List of resource files (one per line) defining other index pages to generate when creating, or updating, an archive. CAUTION It is very important that each resource file specified defines the IDXFNAME (or the TIDXFNAME and THREAD elements for a thread index) to prevent overwriting of the default index pages. MHonArc will only store the name of the resource files listed in the database. Therefore, for any subsequent updates the archive, the extra index resource files must exist inorder to generate the extra index pages. NOTE Since MHonArc will look in the archive location for resource files specified with relative pathnames, you can keep the other index resource files in the same location as the archive, and just specify the filenames for the OTHERINDEXES element in the main resource file. When create resource files for extra indexes, make sure to explicitly set all resources desired since some resource settings may no longer be set to the defaults due to database settings, or from a previously read resource file. Ie. MHonArc does not reset to the default settings when reading in the other resource files. PERLINC Each line represents a path to search when requiring MIME filters. See Specifying Filters in MIME for the use of this element. TFOOT Markup that appears after the thread index listing. See Listing Layout in Thread Index Customization for usage of this element. THEAD Markup that appears before the thread index listing. See Listing Layout in Thread Index Customization for usage of this element. TIDXFNAME The name of the thread index file. The default is "threads.html". TIMEZONES Each line of the TIMEZONES element defines a timezone acronym and its hour offset from UTC/GMT (Universal Coordinate Time). The format of each line is "timezone_acronym:hour_offset". Examples of timezone acronyms are: UTC, PDT, EST. The hour offset is should be positive for timezones West of UTC, and negative for time zones East of UTC. MHonArc has a default list of timezone acronyms defined with hour offsets. Therefore, the list given in the resource file will augment the default list, unless the "Override" attribute is specified. If "Override" is specified, the default list, along with any other lists specified in previous TIMEZONES elements, are discarded, and only the timezone acronyms specified in the TIMEZONES element will be used. The following is the default value for TIMEZONES: <TIMEZONES> UTC:0 GMT:0 AST:4 ADT:3 EST:5 EDT:4 CST:6 CDT:5 MST:7 MDT:6 PST:8 PDT:7 </TIMEZONES> Most of the time, the date used by MHonArc uses a hour offset instead of a timezone acronym. However, mail messages may contain timezone acronyms in received/sent dates and MHonArc must be told what the hour offset from UTC the timezone acronym represents in order to properly sort messages by date. TITLE Title for the main index page. The default is "Mail Index". TLEVELS The maximum number of nested lists for the thread index. The default is 3. TLITXT Markup for an entry in the thread index list. See Listing Layout in Thread Index Customization for usage of this element. TOPLINKS Markup for defining the various hyperlinks at the top of converted messages. See Navigational Links in Message Customization for usage of this element. TTITLE Title for the thread index page. The default is "Mail Thread Index". UMASK Sets the umask for the MHonArc process. The value is treated as an octal number. The resource is only applicable on Unix systems. _________________________________________________________________ Example Resource File  <SORT> <TITLE> MHonArc test </TITLE> <TTITLE> MHonArc test </TTITLE>   <LISTBEGIN> <address> Last updated: $LOCALDATE$ $NUMOFMSG$ messages in chronological order </address> <ul> <li><a href="$TIDXFNAME$">Thread Index</a></li> </ul> Listing format is the following: <ul><li> Subject (# of follow-ups) From </ul> <hr> <ul> </LISTBEGIN>  <LITEMPLATE> <li> $SUBJECT:40$ ($NUMFOLUP$) $FROMNAME$ </LITEMPLATE> <LISTEND> </ul> <hr> <a href="http://foo.org/">Home</a> </LISTEND>  <THEAD> <address> Thread index Last updated: $LOCALDATE$ $NUMOFMSG$ messages </address> <ul> <li><a href="$IDXFNAME$">Main Index</a></li> </ul> <hr> </THEAD>  <EXCS override> apparently errors-to followup forward lines message-id mime- nntp- originator path precedence received replied return-path status via x- </EXCS> <LABELSTYLES> -default- subject:strong from:strong to:strong </LABELSTYLES> <FIELDSTYLES> -default- subject:strong from:strong to:strong keywords:em newsgroups:strong </FIELDSTYLES> <MSGHEAD> <address> MHonArc test archive </address> </MSGHEAD> <MSGFOOT> <a href="http://foo.org/">Home</a> | <a href="$IDXFNAME$">Main Index</a> | <a href="$TIDXFNAME$">Thread Index</a> </MSGFOOT>  <ICONS> application/octet-stream:http://foo.org/icons/binary.xbm application/postscript:http://foo.org/icons/postscript.xbm audio/basic:http://foo.org/icons/sound.xbm image/gif:http://foo.org/icons/image.xbm image/jpeg:http://foo.org/icons/image.xbm image/tiff:http://foo.org/icons/image.xbm multipart/alternative:http://foo.org/icons/alternative.xbm multipart/digest:http://foo.org/icons/text.xbm multipart/mixed:http://foo.org/icons/mixed.xbm multipart/parallel:http://foo.org/icons/mixed.xbm text/richtext:http://foo.org/icons/mixed.xbm text/html:http://foo.org/icons/mixed.xbm text/plain:http://foo.org/icons/text.xbm unknown:http://foo.org/icons/unknown.doc.xbm video/mpeg:http://foo.org/icons/movie.xbm video/quicktime:http://foo.org/icons/movie.xbm </ICONS> _________________________________________________________________ Notes on Resource File * Elements can be duplicated. The following elements augment previous instances of themselves: + EXCS (can specify Override attribute) + FIELDSTYLES + ICONS (can specify Override attribute) + LABELSTYLES + MIMEFILTERS (can specify Override attribute) + PERLINC (can specify Override attribute) + TIMEZONES (can specify Override attribute) The Override attribute will discard previous settings of the element. * If duplicate instances of other elements exist, the last instance takes precedence. * If an element only accepts a single line of content, then the last line is used for the element's content. * If elements have conflicting resource settings (eg. NOSORT and SORT), the last element defined takes precedence. * Resource file settings override environment variables. * Command-line options override any settings in the resource file. * If you want to do an exact match of a field in the EXCS element, append a '$' after the field name. _________________________________________________________________ _________________________________________________________________ ADDING MESSAGES Adding messages to an archive is done via the -add option. If no mailbox/folder arguments are given, MHonArc assumes that a single message is being added to the archive via standard input. Otherwise, MHonArc adds the messages contained in the mail folders specified. NOTE MHonArc will skip any messages that already exist in an archive. If a message to be added has a message-ID that equals a message-ID of an archived message, the message is skipped. _________________________________________________________________ Examples ADDING A MAIL FOLDER Here is example session adding an mail folder to an existing archive: % mhonarc -add test/www Requiring MIME filter libraries ... mhexternal.pl mhtxthtml.pl mhtxtplain.pl mhtxtsetext.pl Adding messages to ./maillist.html Reading test/www/ ........................................ Writing HTML ... 49 messages .FORWARD MHonArc can be used to add new messages as they are received by using the ".forward" file in your home directory. Here is how I would set up my .forward file to invoke MHonArc on incoming mail: \ehood, "|/mnt/ehood/bin/webnewmail #ehood" NOTE on .forward entry: The "\ehood" tells sendmail to still deposit the incoming message to my mail spool file. The "#ehood" Bourne shell comment is needed to insure the command is unique from another user. Otherwise, sendmail may not invoke the program for you or the other user. "webnewmail" is a Perl program that calls MHonArc with the appropriate arguments. A wrapper program is used instead of calling MHonArc directly to keep the .forward file simple. Here is the code to the webnewmail program: #!/usr/local/bin/perl $cmd = "/mnt/ehood/bin/mhonarc -add -quiet " . "-outdir /mnt/ehood/public_html/newmail"; open(M2H, "|$cmd"); print M2H <STDIN>; close(M2H); The webnewmail can be modified to check the mail header before calling MHonArc to perform selective archiving of messages. For example, webnewmail can check the To: field and only archive messages that come from a specific mailing list. CRON This example uses cron(1) to update some mail archives from MH mail folders. The following entry is in my crontab file: 0 0 * * * webmail webmail is a script executed every night that calls MHonArc to perform the update: #! /bin/csh -f umask 022 setenv M2H_RCFILE $HOME/.mhonarc.rc ## WWW messages mhonarc -add \ -outdir $HOME/public_html/doc/wwwmail \ $HOME/mail/www folder +www >& /dev/null refile first-last +www.ar >& /dev/null # Archive original messages ## Tools messages mhonarc -add \ -outdir $HOME/public_html/doc/toolsmail \ $HOME/mail/tools $HOME/mail/dtd folder +tools >& /dev/null refile first-last +tools.ar >& /dev/null # Archive original messages folder +dtd >& /dev/null refile first-last +dtd.ar >& /dev/null # Archive original messages folder +inbox >& /dev/null # Set current folder to inbox To avoid mail everynight from cron due to output from MHonArc, the -quiet option can be used for each call to MHonArc, or use the following line in your crontab file: 0 0 * * * webmail > /dev/null Standard error is not redirected to /dev/null so mail is still received if errors occured during MHonArc execution. _________________________________________________________________ _________________________________________________________________ REMOVING MESSAGES Removing messages from an archive is done via the -rmm option. Messages to be deleted are designated by message numbers on the command-line. Example % mhonarc -rmm 24 28 39 48 Removing messages from ./maillist.html ... Removing message 24 Removing message 28 Removing message 39 Removing message 48 Writing mail ... Writing tmp/maillist.html ... Writing tmp/threads.html ... 45 messages _________________________________________________________________ Message Numbers Normally, you will never have to worry about message numbers unless you want to remove messages from an archive. Therefore, you will need to know how MHonArc assigns message numbers when processing messages. When a message is processed, the smallest available number is assigned to it, starting with 0. The number assigned to a message becomes part of the filename for the HTML version of the message (eg. msg00042.html). To avoid message number conflicts, MHonArc determines the smallest available number by finding the largest assigned number and adding one to it. _________________________________________________________________ Scanning an Archive You will quickly find out that finding the message numbers for a messages you want to remove can be a cumbersome task if all you have to work with are the message filenames. To ease this task, MHonArc gives you the ability to scan an archives contents via the -scan command-line option. EXAMPLE % mhonarc -scan 100 messages in .: Msg # YY/MM/DD From Subject ----- -------- --------------- --------------------------------------------- 513 95/02/09 Rick Silterra EDComment(sic) 517 95/02/09 Earl Hood Re: DTD2HTML 512 95/02/09 Earl Hood Re: edc2html 516 95/02/09 John Barnum Re: DTD2HTML 515 95/02/09 Earl Hood Re: DTD2HTML 511 95/02/09 Rick Silterra edc2html 514 95/02/08 John Barnum DTD2HTML 510 95/02/06 jflores mhonarc_diagnostics.doc.html 509 95/02/06 web Dr.Web: Status Review + Thank You 508 95/02/05 Earl Hood Re: sgml to html converters 507 95/02/03 Aileen Barry sgml to html converters 506 95/01/28 Earl Hood Re: MHonarc: Deleting Messages from an archiv 505 95/01/28 Floyd Moore MHonarc: Deleting Messages from an archive 504 95/01/25 Earl Hood Re: MHonArc 503 95/01/25 Earl Hood Re: MHonArc ... The messages are listed in the same order as they are listed in the archive's index page. You will notice that the list order does not necessarily correspond with message number order. If you always want the messages listed in message number order when scanning, use the following: % mhonarc -scan -nosort -noreverse 82 messages in .: Msg # YY/MM/DD From Subject ----- -------- --------------- --------------------------------------------- 0 94/05/09 Michael O´Sulli Re: Finger within an html 1 94/04/31 John M. Troyer Re: TROFF to HTML Converters 2 94/05/04 John D. Kilburg ANNOUNCE: Chimera 1.53 3 94/05/17 Stephen Billing Re: government www? 4 94/05/21 C. Emory Tate Re: government www? 5 94/05/24 Daniel W. Conno Re: Comments on HTML 2.0 document/DTD 6 94/05/24 Dan Connolly Re: Validating HTML documents: 7 94/05/25 Henrik Frystyk CERN Common World-Wide Web Library 2.16pre2 A 8 94/06/04 Denesh Bhabuta Re: Atari on www (revisited) 9 94/06/07 Dale Newfield ANNOUNCE: Come explore The Edge - SIGGRAPH 94 10 94/06/11 Roy T. Fielding Announcing libwww-perl 0.12 ... _________________________________________________________________ _________________________________________________________________ INDEX PAGE CUSTOMIZATION MHonArc creates an index page with links to all mail messages filtered (unless processing a single message with the -single option). MHonArc allows you to have complete customization over the appearance of the index page by setting various resource either through environment variables, command-line options, or the resource file. _________________________________________________________________ Filename By default, the filename of the index page is "maillist.html". However, a different name may be specified with the M2H_IDXFNAME environment variable, the IDXFNAME resource element, or the -idxfname command-line option. _________________________________________________________________ Beginning Markup MHonArc allows you to completely override the begining markup of the index page. I.e. You can control the opening <HTML> tag, the HEAD element contents, the opening <BODY> tag, etc. Therefore, if you are not satisfied with the default behavior of how the TITLE resource is used, or have other needs that require control on the beginning markup, you can set the IDXPGBEGIN resource file element. IDXPGBEGIN The best way to show how the IDXPGBEGIN works, the following represents the default setting MHonArc uses: <IDXPGBEGIN> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> <HTML> <HEAD> <TITLE>$IDXTITLE$</TITLE> </HEAD> <BODY> <H1>$IDXTITLE$</H1> </IDXPGBEGIN> NOTE Technically, setting the TITLE resource, via the M2H_TITLE environment variable, the TITLE resource element, or the -title command-line option, sets the $IDXTITLE$ resource file variable. The resource variables allowed in the IDXPGBEGIN element are the following: * $DOCURL$ -- URL to documentation * $GMTDATE$ -- Current GMT date. * $IDXFNAME$ -- Filename of main index page. * $IDXSIZE$ -- Max number of messages that may be listed in the index. * $IDXTITLE$ -- The title of the index page. * $LOCALDATE$ -- Current local date. * $NUMOFIDXMSG$ -- Number of message listed. * $NUMOFMSG$ -- Number of messages in the archive. * $OUTDIR$ -- Pathname of archive. * $PROG$ -- Program name. * $TIDXFNAME$ -- Filename of thread index page. * $TIDXTITLE$ -- Title of thread index page. * $VERSION$ -- Program version. See Resource Variables for more information on the usage of variables. _________________________________________________________________ End Markup Since MHonArc allows you to control the beginning markup, it makes sense for it to allow you to control the ending markup. IDXPGEND The IDXPGEND resource element may be used to define the ending markup of the index page. The default value is the following: <IDXPGEND> </BODY> </HTML> </IDXPGEND> The resource variables allowed are the same as for IDXPGBEGIN. _________________________________________________________________ Include Files MHonArc allows you to include the contents of files into the index page via the header and footer resources. NOTE The use of include files is discouraged since the LISTBEGIN and LISTEND resources can be used to achieve the same results. Also, the support for the include resource may be removed in future releases. The header file is specified via the M2H_HEADER environment variable, the HEADER resource element, or the -header command-line option. The contents of the header file are inserted above the message listing, and right after the H1 title element. NOTE Filename should not contain the <HTML>, <HEAD>, and <BODY> tags; these tags are automatically provided by MHonArc, or defined by the IDXPGBEGIN resource file element. The footer file is specified via the M2H_FOOTER environment variable, the FOOTER resource element, or the -footer command-line option. The contents of the footer file are inserted after the message listing. NOTE Filename should not contain the </BODY>, and </HTML> tags; these tags are automatically provided by MHonArc, or defined by the IDXPGEND resource file element. The header and footer files allow you to incorporate search-forms, hyperlinks to other pages, or any other HTML markup you like. It is only necessary to specify the header and/or footer files the first time you create an archive. The contents included from the header and/or footer files are preserved in any subsequent additions to the archive. Only respecify the header and/or footer files if you need to make changes to the header/footer contents. _________________________________________________________________ Listing Layout MHonArc lists messages in the order specified by the various sort options. However, you have complete control on how the message listing are formatted via the LISTBEGIN, LITEMPLATE, and LISTEND resource elements in the Resource File. These elements allow you to specify the HTML markup to use in the index page. LISTBEGIN The LISTBEGIN resource element specifies the text to begin the message list. The text can be any valid HTML markup. Plus, MHonArc defines the following variables you may use which get expanded at run-time: * $DOCURL$ -- URL to documentation * $GMTDATE$ -- Current GMT date. * $IDXFNAME$ -- Filename of main index page. * $IDXSIZE$ -- Max number of messages that may be listed in the index. * $IDXTITLE$ -- The title of the index page. * $LOCALDATE$ -- Current local date. * $NUMOFIDXMSG$ -- Number of message listed. * $NUMOFMSG$ -- Number of messages in the archive. * $OUTDIR$ -- Pathname of archive. * $PROG$ -- Program name. * $TIDXFNAME$ -- Filename of thread index page. * $TIDXTITLE$ -- Title of thread index page. * $VERSION$ -- Program version. MHonArc's LISTBEGIN default value is the following: <LISTBEGIN> <UL> <LI><A HREF="$TIDXFNAME$">Thread Index</A></LI> </UL> <HR> <UL> </LISTBEGIN> If the NOTHREAD resource is set, the following is the default value: <LISTBEGIN> <HR> <UL> </LISTBEGIN> LITEMPLATE The LITEMPLATE resoure element defines the HTML text to represent each message list item. You may use the following variables which are expanded at runtime: * $A_ATTR$ -- The NAME and HREF attributes to use in an anchor to link to the archived message. The NAME attribute links the messages to the index page. * $A_HREF$ -- The HREF attribute to use in an anchor to link to the archived message. * $A_NAME$ -- The NAME attributes to use in an anchor for messages to link to the index page. * $DATE$ -- The date of the message. * $DDMMYY$ -- Message date in dd/mm/yy format. * $ICON$ -- The context-type sensistive icon. See Icons for information. * $ICONURL$ -- The URL to the context-type sensistive icon. See Icons for information. * $MMDDYY$ -- Message date in mm/dd/yy format. * $NUMFOLUP$ -- Number of follow-ups for the given message. * $FROM$ -- The complete text in the From: field of the message. * $FROMADDR$ -- The e-mail address in the From: field of the message. * $FROMNAME$ -- The English name of the person in the From: field of the message. If no English name is found, the username specified in the e-mail address is used. * $MSGNUM$ -- The message numbers assigned to the message by MHonArc. * $ORDNUM$ -- The current listing number of the message. * $SUBJECT$ -- The subject text of the message wrapped in an anchor element that hyperlinks to the message. * $SUBJECTNA$ -- The subject text of the message without the anchor element. * $YYMMDD$ -- Message date in yy/mm/dd format. NOTE Do not specify $A_ATTR$, $A_NAME, and $SUBJECT$ together in the LITEMPLATE element. Since all of these variables contain the NAME atrribute. Invalid HTML will be created since multiple anchors will have the same NAME identifier. LITEMPLATE's default value is the following: <LITEMPLATE> <LI>$SUBJECT$ <UL><LI>From: $FROM$</LI></UL> </LI> </LITEMPLATE> LISTEND The LISTEND resource element specifies the text to use to end the message list. The text can be any valid HTML markup. LISTEND may contain the same variables as LISTBEGIN. LISTEND's default value is the following: <LISTEND> </UL> </LISTEND> _________________________________________________________________ Icons MHonArc supports the ability to insert icons in the index page for each message based on the message's content-type. For example: You can have text/plain messages use a different icon than text/html messages. DEFINING ICONS To specify the icons for MHonArc to use, you use the ICONS resource element in the Resource File. The format of each line in the ICONS element is as follows: <content-type>:<URL for icon> <content-type> represents a MIME content-type. <URL for icon> is the URL to the icon. The special content-type called "unknown" may be defined to specify the icon to use for non-recognized content-types. If unknown is not defined, the text/plain icon is used for unknown content types. Example <ICONS> audio/basic:http://foo.org/gifs/gsound.gif image/gif:http://foo.org/gifs/gimage.gif image/jpeg:http://foo.org/gifs/gimage.gif image/tiff:http://foo.org/gifs/ggraphic.gif multipart/alternative:http://foo.org/gifs/gmulti.gif multipart/digest:http://foo.org/gifs/gtext.gif multipart/mixed:http://foo.org/gifs/gdoc2.gif multipart/parallel:http://foo.org/gifs/gdoc.gif text/richtext:http://foo.org/gifs/gdoc.gif text/html:http://foo.org/gifs/gdoc.gif text/plain:http://foo.org/gifs/gletter.gif unknown:http://foo.org/gifs/gunknown.gif video/mpeg:http://foo.org/gifs/gmovie.gif </ICONS> USING ICONS In order to incorporate icons into the index page, insert the $ICON$ variable into the LITEMPLATE resource element. Example <litemplate> $ICONURL$$SUBJECT:40$ ($NUMFOLUP$) $FROMNAME$ </litemplate> The $ICON$ variable expands to the IMG HTML element with the appropriate URL in the SRC attribute to the icon. The ALT attribute of the IMG element contains the content-type of the message, surrounded by []'s, for use with text based browsers. $ICONURL$ may also be used if you want redefine the format of the IMG element. Example <litemplate> <img src="$ICONURL$" alt="* ">$SUBJECT:40$ ($NUMFOLUP$) $FROMNAME$ </litemplate> This example overrides what is normally used in the ALT attribute. _________________________________________________________________ Examples EXAMPLE 1 It may be easier to see how the LISTBEGIN, LITEMPLATE, LISTEND resource elements work when declared together:  <LISTBEGIN> <UL> <LI><A HREF="$TIDXFNAME$">Thread Index</A></LI> </UL> <HR> <UL> </LISTBEGIN> <LITEMPLATE> <LI>$SUBJECT$ <UL><LI>From: $FROM$</LI></UL> </LI> </LITEMPLATE> <LISTEND> </UL> </LISTEND> EXAMPLE 2 Here's another example that changes the layout into a more compact listing, adds Icons usage, and adds a time stamp information on when the index page was last updated: <listbegin> <address> Last update: $CURDATE$ $NUMOFMSG$ messages </address> <UL> <LI><A HREF="$TIDXFNAME$">Thread Index</A></LI> </UL> Messages listed in chronological order. Listing format is the following: <blockquote> <img src="http://foo.org/gifs/gletter.gif" alt="* "> Subject (# of follow-ups) From. </blockquote> <hr> </listbegin> <litemplate> <img src="$ICONURL$" alt="* ">$SUBJECT:40$ ($NUMFOLUP$) $FROMNAME$ </litemplate> <listend> </listend> _________________________________________________________________ _________________________________________________________________ MESSAGE CUSTOMIZATION This sections shows how to customize the appearance of messages when converted to HTML. _________________________________________________________________ Beginning Markup MHonArc allows you to completely override the begining markup of the message pages. I.e. You can control the opening <HTML> tag, the HEAD element contents, the opening <BODY> tag, etc. Therefore, if you are not satisfied with the default markup used, or have other needs that require control on the beginning markup, you can set the MSGPGBEGIN resource file element. MSGPGBEGIN The MSGPGBEGIN resource file element has the default value: <MSGPGBEGIN> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> <HTML> <HEAD> <TITLE>$SUBJECTNA:72$</TITLE> <LINK REV="made" HREF="mailto:$FROMADDR$"> </HEAD> <BODY> </MSGPGBEGIN> The following variables may be used in the MSGPGBEGIN element: * $DATE$ -- Message date. * $DDMMYY$ -- Message date in dd/mm/yy format. * $DOCURL$ -- URL to documentation. * $FROM$ -- Contents of From field of message. * $FROMADDR$ -- E-mail address contained in From field of message. * $FROMNAME$ -- "English" name contained in From field of message. * $GMTDATE$ -- Current GMT date. * $IDXFNAME$ -- Filename of main index page. * $IDXSIZE$ -- Max number of messages that may be listed in the index. * $IDXTITLE$ -- The title of the index page. * $LOCALDATE$ -- Current local date. * $MMDDYY$ -- Message date in mm/dd/yy format. * $MSGID$ -- Message ID of message. * $MSGNUM$ -- Number assigned to message by MHonArc. * $NUMOFIDXMSG$ -- Number of message listed. * $NUMOFMSG$ -- Number of messages in the archive. * $OUTDIR$ -- Pathname of archive. * $PROG$ -- Program name. * $SUBJECTNA$ -- Message subject text. * $TIDXFNAME$ -- Filename of thread index page. * $TIDXTITLE$ -- Title of thread index page. * $VERSION$ -- Program version. * $YYMMDD$ -- Message date in yy/mm/dd format. _________________________________________________________________ End Markup The ending markup of messages can be controlled by the MSGPGEND resource file element. MSGPGEND The MSGPGEND resource element may be used to define the ending markup of the message pages. The default value is the following: <MSGPGEND> </BODY> </HTML> </MSGPGEND> The resource variables allowed are the same as for MSGPGBEGIN. _________________________________________________________________ Header and Footer The MSGHEAD resource represents HTML text that should be inserted at the very beginning of each converted message. The MSGFOOT resource represents HTML text that should be appended to the end of each converted message. The default value for both resources is empty. The following variables may be used in the MSGHEAD and MSGFOOT content: * $DATE$ -- Message date. * $DDMMYY$ -- Message date in dd/mm/yy format. * $DOCURL$ -- URL to documentation. * $FROM$ -- Contents of From field of message. * $FROMADDR$ -- E-mail address contained in From field of message. * $FROMNAME$ -- "English" name contained in From field of message. * $GMTDATE$ -- Current GMT date. * $IDXFNAME$ -- Filename of main index page. * $IDXSIZE$ -- Max number of messages that may be listed in the index. * $IDXTITLE$ -- The title of the index page. * $LOCALDATE$ -- Current local date. * $MMDDYY$ -- Message date in mm/dd/yy format. * $MSGID$ -- Message ID of message. * $MSGNUM$ -- Number assigned to message by MHonArc. * $OUTDIR$ -- Pathname of archive. * $PROG$ -- Program name. * $SUBJECTNA$ -- Message subject text. * $TIDXFNAME$ -- Filename of thread index page. * $TIDXTITLE$ -- Title of thread index page. * $VERSION$ -- Program version. * $YYMMDD$ -- Message date in yy/mm/dd format. _________________________________________________________________ Navigational Links MHonArc gives you the ability to control the layout of the navigational links for each message page. Navigational links include links to previous and next messages, link to main index, link to thread index, etc. The layout of the navigational links are controlled by two resource file elements: TOPLINKS and BOTLINKS. TOPLINKS The TOPLINKS resource element defines the layout of the navigational links at the top of each message page. The markup defined, will appear after the MSGHEAD data and before the filtered message data. The default value for TOPLINKS is the following: <TOPLINKS> <HR> $PREVBUTTON$$NEXTBUTTON$<A HREF="$IDXFNAME$#$MSGNUM$">[Index]</A><A HREF="$TIDXFNAME$#$MSGNUM$">[Thread]</A> </TOPLINKS> If no thread index is specified, then the thread link markup is removed. The following variables are available: * $DATE$ -- Message date. * $DDMMYY$ -- Message date in dd/mm/yy format. * $DOCURL$ -- URL to documentation. * $FROM$ -- Contents of From field of message. * $FROMADDR$ -- E-mail address contained in From field of message. * $FROMNAME$ -- "English" name contained in From field of message. * $GMTDATE$ -- Current GMT date. * $IDXFNAME$ -- Filename of main index page. * $IDXSIZE$ -- Max number of messages that may be listed in the index. * $IDXTITLE$ -- The title of the index page. * $LOCALDATE$ -- Current local date. * $MMDDYY$ -- Message date in mm/dd/yy format. * $MSGID$ -- Message ID of message. * $MSGNUM$ -- Number assigned to message by MHonArc. * $NEXTBUTTON$ -- Next button markup. See Conditional Links for more information. * $NEXTFROM$ -- Contenst of From field of the next message according to the list order of the main index. * $NEXTFROMADDR$ -- E-mail address contained in From field of the next message according to the list order of the main index. * $NEXTFROMNAME$ -- English" name contained in From field of the next message according to the list order of the main index. * $NEXTLINK$ -- Next link markup. See Conditional Links for more information. * $NEXTMSG$ -- Filename of next message according to the list order of the main index. * $NEXTMSGNUM$ -- Number assigned to next message according to the list order of the main index. * $NEXTSUBJECT$ -- Subject of next message according to the list order of the main index. * $NUMOFIDXMSG$ -- Number of message listed. * $NUMOFMSG$ -- Number of messages in the archive. * $PREVBUTTON$ -- Previous button markup. See Conditional Links for more information. * $PREVFROM$ -- Contenst of From field of the previous message according to the list order of the main index. * $PREVFROMADDR$ -- E-mail address contained in From field of the previous message according to the list order of the main index. * $PREVFROMNAME$ -- English" name contained in From field of the previous message according to the list order of the main index. * $PREVLINK$ -- Previous link markup. See Conditional Links for more information. * $PREVMSG$ -- Filename of previous message according to the list order of the main index. * $PREVMSGNUM$ -- Number assigned to previous message according to the list order of the main index. * $PREVSUBJECT$ -- Subject of previous message according to the list order of the main index. * $PROG$ -- Program name. * $SUBJECTNA$ -- Message subject text. * $TIDXFNAME$ -- Filename of thread index page. * $TIDXTITLE$ -- Title of thread index page. * $VERSION$ -- Program version. * $YYMMDD$ -- Message date in yy/mm/dd format. BOTLINKS The BOTLINKS resource element defines the layout of the navigational links at the bottom of each message page. The markup defined, will appear after the filtered message data and any thread links, and before the MSGFOOT data. The default value for BOTLINKS is the following: <BOTLINKS> <HR> <UL> $PREVLINK$ $NEXTLINK$ <LI>Index(es): <UL> <LI><A HREF="$IDXFNAME$#$MSGNUM$">Main</A></LI> <LI><A HREF="$TIDXFNAME$#$MSGNUM$">Thread</A></LI> </BOTLINKS> If no thread index is specified, then the thread link markup is removed. The variables available for BOTLINKS are the same as for TOPLINKS. CONDITIONAL LINKS Since the state of some navigational links can change due the position of the message in the archive (eg. first and last messages), special resources exist that allows you to control the markup of some of the links based upon if the link is valid or not for a given message. The resource elements for defining the conditional links are the following: PREVBUTTON, NEXTBUTTON, PREVLINK, and NEXTLINK, and their inactive counterparts, PREVBUTTONIA, NEXTBUTTONIA, PREVLINKIA, and NEXTLINKIA. The appropriate value of these elements (ie. if it is active, or inactive) are represented by the $PREVBUTTON$, $NEXTBUTTON$, $PREVLINK$, and $NEXTLINK$ resource file variables, respectively, which may be used in other resource elements' contents (TOPLINKS and BOTLINKS in particular). The defaults values for each conditional link resource is as follows: PREVBUTTON <PREVBUTTON> <A HREF="$PREVMSG$">[Prev]</A> </PREVBUTTON> NEXTBUTTON <NEXTBUTTON> <A HREF="$NEXTMSG$">[Next]</A> </NEXTBUTTON> PREVLINK <PREVLINK> <LI>Prev: <A HREF="$PREVMSG$">$PREVSUBJECT$</A></LI> </PREVLINK> NEXTLINK <NEXTLINK> <LI>Next: <A HREF="$NEXTMSG$">$NEXTSUBJECT$</A></LI> </NEXTLINK> All the "IA" elements default to empty content. NOTE The last newline for the PREVBUTTON, NEXTBUTTON, PREVBUTTONIA, and NEXTBUTTONIA elements is ignored by MHonArc. This allows a "tight" grouping of button links; ie. no space between buttons. If you desire to have a newline in the content, just insert a trailing blank line at the end of the element's content. You should note that there is a correlation between the value of the conditional links elements and the contents of the TOPLINKS and BOTLINKS elements. The following variables may be used within the conditional link elements. * $NEXTFROM$ -- Contenst of From field of the next message according to the list order of the main index. * $NEXTFROMADDR$ -- E-mail address contained in From field of the next message according to the list order of the main index. * $NEXTFROMNAME$ -- English" name contained in From field of the next message according to the list order of the main index. * $NEXTMSG$ -- Filename of next message according to the list order of the main index. * $NEXTMSGNUM$ -- Number assigned to next message according to the list order of the main index. * $NEXTSUBJECT$ -- Subject of next message according to the list order of the main index. * $PREVFROM$ -- Contenst of From field of the previous message according to the list order of the main index. * $PREVFROMADDR$ -- E-mail address contained in From field of the previous message according to the list order of the main index. * $PREVFROMNAME$ -- English" name contained in From field of the previous message according to the list order of the main index. * $PREVMSG$ -- Filename of previous message according to the list order of the main index. * $PREVMSGNUM$ -- Number assigned to previous message according to the list order of the main index. * $PREVSUBJECT$ -- Subject of previous message according to the list order of the main index. WARNING Never include conditional link variables ($PREVBUTTON$, $NEXTBUTTON$, $PREVLINK$, and $NEXTLINK$) in conditional link element content. This will cause an infinite loop during execution and will eventually lead to a crash due to a lack of memory. _________________________________________________________________ Message Layout Defining the format for the actual mail message data is divided into two parts: the message head and the message body. Customizing the message header markup is described in this section, but due to the nature of how messages are processed, the message body format is controlled by the various MIME filters directly (see the section on MIME for further details). EXCLUDING FIELDS The EXCS resource allows you to specify what fields should be excluded in the HTML output. EXCS Each line of the EXCS element specifies a mail header field to exclude in the converted HTML output. Each line is treated as a Perl regular expression (NOTE: the regular expression is already anchored to the begining of the line). The default value for EXCS is the following: <EXCS> content- errors-to forward lines message-id mime- nntp- originator path precedence received replied return-path status via x- </EXCS> Any fields you specify for the EXCS resource will augment the default list, unless the "Override" attribute is specified. If "Override" is specified, the default list is discarded along with any other lists specified from previous EXCS elements; and only header fields specified in the EXCS element are excluded. FIELD ORDER The FIELDORDER resource allows you to control the order the message header fields appear in the HTML output. FIELDORDER Each line of the FIELDORDER element is the exact case-insensitive name of a message header field. The order the fields are listed is the order they will appear in the filtered message. The special field value "-extra-" represents all fields not explicitly specified in the FIELDORDER element and not excluded by the EXCS element. Extra fields are listed in sorted order. The following represents the default value of the FIELDORDER resource: <FIELDORDER> to subject from date -extra- </FIELDORDER> FIELD FORMATTING The FIELDSTYLES and LABELSTYLES resources allow to control how each message header field is formatted. FIELDSTYLES Each line in the FIELDSTYLES element defines HTML elements to wrap around the field text in mail headers (e.g. "To: field text", "From: field text"). The format of each line is "field_name:html_element". This specifies to wrap html_element around the text associated with field_name. If html_element is empty, then the field text is not wrapped in any element. MHonArc defines a special field_name called "-default-". This is default HTML element to wrap field text in if no explicit specific element is defined for the label. field_name must be the exact name of a header field name, but character case is ignored. The default value of FIELDSTYLES is the following: <FIELDSTYLES> -default- </FIELDSTYLES> LABELSTYLES Each line in the LABELSTYLES element defines HTML elements to wrap around labels in mail headers (e.g. "To:", "From:"). The format of each line is "field_name:html_element". This specifies to wrap html_element around field_name. If html_element is empty, then the label is not wrapped in any element. MHonArc defines a special field_name called "-default-". This is default HTML element to wrap a label in if no explicit specific element is defined for the label. field_name must be the exact name of a header field name, but character case is ignored. The default value of LABELSTYLES is the following: <LABELSTYLES> -default-:em </LABELSTYLES> _________________________________________________________________ Other Resources E-MAIL LINKS MAILTOURL URL to use for e-mail address hyperlinks in e-mail message header fields. The following variables are defined for the MAILTOURL resource: * $FROM$ -- Who the message is from. * $MSGID$ -- Message ID of the message. * $SUBJECT$ -- The subject of the message. * $TO$ -- Destination e-mail address of link. MHonArc will use the following URL by default: "mailto:$TO$". NOTE The MAILTOURL resource has different rules for variable expansion. If a variable does not exactly match the set of variables available for the MAILTOURL, the variable text will be taken literally as part of the element content. Therefore, a single "$" can be used to represent a "$" character. Also, variables in the MAILTOURL should NOT have ":NU" modifier. This will prevent the variables from be recognized. MHonArc will automatically treat the replacement value as a part of a URL string. _________________________________________________________________ _________________________________________________________________ MIME MHonArc has support for e-mail messages with Multipurpose Internet Mail Extensions (MIME) as defined in RFC 1521. MHonArc handles the filtering of the various content-types used in MIME in a modular fashion. Since new content-types are occasionally defined for MIME, this modularity allows users to add new filters to accomodate new content-types. Also, filters can be hooked in to override MHonArc's default filters, or provide MHonArc with the ability to process existing content-types that it cannot handle currently. _________________________________________________________________ Default Filters The default filters provided by MHonArc supports the following MIME content-types, which may be overriden by user-defined filters: * application/* * audio/* * image/* * message/news * message/partial * message/rfc822 * multipart/alternative * multipart/digest * multipart/mixed * multipart/parallel * text/html * text/plain * text/setext * video/* For more information on how to write your filters, or replace existing filters, see Writing Filters. The next sections describes how MHonArc processes the content-types listed above. APPLICATION/* MHonArc extracts the data into a separate file and puts a hyperlink to the file into the HTMLized message. By default, MHonArc ignores any filename specification (the "name" attribute as defined in the Content-Type header field) given in the message when writing the data to disk. MHonArc generates a unique filename with an extenstion based upon sub-type. If you want MHonArc to use the filename, then you can use the MIMEARGS resource and specify an argument string of "usename". Example: <MIMEARGS> application/postscript:usename </MIMEARGS> If you want MHonArc to use specified filename for all application types, then use the following: <MIMEARGS> application/*:usename </MIMEARGS> CAUTION The use of "usename" is discouraged since it can lead to filename conflicts and security problems. Here is the current list of application sub-types (with their filename extensions) supported by MHonArc: * mac-binhex40 (hqx) * octet-stream (bin) * oda (oda) * pdf (pdf) * postscript (ps) * rtf (rtf) * x-bcpio (bcpio) * x-cpio (cpio) * x-csh (csh) * x-dvi (dvi) * x-gtar (gtar) * x-hdf (hdf) * x-latex (latex) * x-mif (mif) * x-netcdf (cdf) * x-patch (no extension; processed by the text/plain filter) * x-sh (sh) * x-shar (shar) * x-sv4cpio (sv4cpio) * x-sv4crc (sv4crc) * x-tar (tar) * x-tcl (tcl) * x-tex (tex) * x-texinfo (texinfo) * x-troff (roff) * x-troff-man (man) * x-troff-me (me) * x-troff-ms (ms) * x-ustar (ustar) * x-wais-source (src) * zip (zip) AUDIO/* MHonArc extracts the data into a separate file and puts a hyperlink to the file into the HTMLized message. The name of the file created follows the same guidelines mentioned under application/*. Here is the current list of audio sub-types (with their filename extensions) supported by MHonArc: * basic (snd) * x-aiff (aif) * x-wav (wav) IMAGE/* MHonArc will extract the data into a separate file and puts a hyperlink to the file into the HTMLized message. The name of the file created follows the same guidelines mentioned under application/*. In addition to the filename specification mentioned under application/*, an "inline" argument may be declared to instruct MHonArc to inline the image in the generated HTML. Example: <MIMEARGS> image/gif:inline </MIMEARGS> The following examples says to inline XBM images and use the name attribute as the filename if defined: <MIMEARGS> image/x-xbm:inline usename </MIMEARGS> The following represents the default argument settings used by MHonArc: <MIMEARGS> image/gif:inline image/x-xbitmap:inline image/x-xbm:inline </MIMEARGS> Here is the current list of image sub-types (with their filename extensions) supported by MHonArc: * gif (gif) * ief (ief) * jpeg (jpg) * tiff (tif) * x-bmp (bmp) * x-cmu-raster (ras) * x-pcx (pcx) * x-pict (pict) * x-portable-anymap (pnm) * x-pnm (pnm) * x-portable-bitmap (pbm) * x-pbm (pbm) * x-portable-graymap (pgm) * x-pgm (pgm) * x-portable-pixmap (ppm) * x-ppm (ppm) * x-rgb (rgb) * x-xbitmap (xbm) * x-xbm (xbm) * x-xpixmap (xpm) * x-xpm (xpm) * x-xwindowdump (xwd) * x-xwd (xwd) If the image is a GIF or XBM (X bitmap), the HTML IMG element will be used to in-line the image into the HTMLized message. MESSAGE/NEWS message/news signifies an included (MIME) USENET news message. The data associated with a message/news part is processed by MHonArc in the same manner as a regular mail message. MESSAGE/PARTIAL message/partial signifies that the content is a single part of a message split into multiple mail messages. message/partial is treated in the same manner as text/plain. MESSAGE/RFC822 message/rfc822 signifies an included (MIME) mail message. The data associated with a message/rfc822 part is processed by MHonArc in the same manner as a regular mail message. MULTIPART/ALTERNATIVE multipart/alternative signifies multiple content-types with the same (or similiar) information. MHonArc processes only the latest part that has a content-type filter. MULTIPART/DIGEST mulltipart/digest signifies a series of included mail messages. Each part is processed in the same manner as message/rfc822 unless an explicit content-type is specifed for each part. MULTIPART/MIXED multipart/mixed signifies data with multiple content-types. MHonArc extracts each part and calls the appropriate content-type filter for each part, if defined. MULTIPART/PARALLEL multipart/parallel is processed in the same manner as multipart/mixed. TEXT/HTML text/html signifies that the data is HTML markup. The data as left "as is" with the exception of some processing to legally include the HTML into the HTMLized mail message. I.e. MHonArc removes the HEAD an BODY tags, the TITLE element will be replaced with an ADDRESS element surrounded by HR's, and the BASE element URL will be propogated to relative URLs. TEXT/PLAIN text/plain signifies ASCII character data. In the HTMLized message, the data is wrapped in a PRE element with special characters (< > &) converted to entity references. MHonArc will also make any URLs into hyperlinks. The following URL types are recognized: * http://... * ftp://... * afs://... * wais://... * telnet://... * gopher://... * news:... * nntp:... * mid:... * cid:... * mailto:... * prospero:... TEXT/SETEXT text/setext signifies "structure enhanced text". The data is converted into HTML containing hyperlinks as defined by the setext data. For more information on setext, see <URL:http://www.bsdi.com/setext/>. VIDEO/* MHonArc extracts the data into a separate file and puts a hyperlink to the file into the HTMLized message. The name of the file created follows the same guidelines mentioned under application/*. Here is the current list of video sub-types (with their filename extensions) supported by MHonArc: * mpeg (mpg) * quicktime (mov) * x-msvideo (avi) * x-sgi-movie (movie) _________________________________________________________________ Non-MIME Messages Messages that do not contain a MIME Content-Type header field are processed as text/plain messages. _________________________________________________________________ Writing Filters If you want to write your own filter for use in MHonArc, you need to know the Perl programming language. The following information assumes you know Perl. To learn how to hook in your filters into MHonArc, see Specifying Filters. FUNCTION INTERFACE OF FILTER MHonArc interfaces with MIME filters by calling a routine with a specific set of arguments. The prototype of the interface routine is as follows: sub filter { local($head, *fields, $data, $decoded, $argstring) = @_; # Filter code here # The last statement should be the return value, unless an # explicit return is done. See the following for the format of the # return value. } Argument Descriptions $head This is the header text of the message (or body part if called in a mulitpart message). *fields This is a pointer to an associative array that has broken down $head into field label/field value components. The keys are the lower-case representations of the field values. Example: If you would like to retrieve the value of the Content-Type field, then use the following: $fields{`content-type'}. If a field occurs more than once in a header, MHonArc separates the field values in the associative array by a `\034' character. To make your filter less likely to break due to changes in MHonArc, you may use the $'X variable instead of `\034'. $data This is a copy of the message (or body part if called in a mulitpart message) body. $decoded This flag is set to 1 if MHonArc decoded the message and $data represents the orginal data before encoded by the sender. If set to 0, $data has not been decoded. The failure to decode occurs if MHonArc does not recognizeed the encoding specified in the Content-Transfer-Encoding field. MHonArc has decoded the data for you if it was encoded in 7-Bit, 8-Bit, Binary, Quoted-Printable, Base64, or X-Uuencode. $argstring This is an optional argument string that may be used to modify the behavior of the filter. The format of this string is determined by the filter itself. The value of the string is set by the MIMEARGS resource. Return Value The return value is treated as an array. The first item in the array is a string representing the HTML markup to insert in the HTMLized message. An empty string may be returned to tell MHonArc that the routine was unable to filter data. Any other array items are treated as names of any files that were generated by the filter. MHonArc needs to keep track if any extra files that a filter may generate in order for MHonArc to delete those files if the message gets removed from the archive. FILTER WRITING TIPS The following recommendations/tips are given to help you write filters: * Qualify your filter in its own package. This eliminates possible variable/routine conflicts with MHonArc. * If the filter creates derived files (like the image filters), you may use the variable $'OUTDIR to determine the location of the mail archive. NOTE: Do not include $'OUTDIR as part as the filename that is returned to MHonArc. If the filter does create files, just return the base name. * Look at the default filters contained in the distribution of MHonArc. You can use these as templates for writing your own. * Make sure your Perl source file ends with a true statement (like "1;"). MHonArc just performs a require on the file, and if the file does not return true, Perl will abort execution. USING C If a MIME filter requires the utilization of a C program, or other non-Perl executable, a Perl wrapper must be written for the program in-order to interface with MHonArc. The wrapper must follow the rules as specified in Function Interface of Filter. _________________________________________________________________ Specifying Filters Adding new filters, or overriding existing ones, are done via the Resource File. The two resources for specifying and controlling MIME filters are MIMEFILTERS and MIMEARGS. MIMEFILTERS The resource element MIMEFILTERS in the Resource File is used to hook in user specifed filters into MHonArc. The syntax for each line of the the MIMEFILTERS element is as follows: <content-type>:<routine-name>:<file-of-routine> The definition of each colon-separated value is as follows: <content-type> The MIME content-type the filter processes. <routine-name> The actual routine name of the filter. The name should be fully qualified by the package it is definedi (e.g. "mypackage'filter"). <file-of-routine> The name of the file that defines <routine-name>. If the file is not a full pathname, MHonArc finds the file by looking in the standard include paths of Perl, and the paths specified by the PERLINC resource element. Any whitespace is stripped out before processing. Example The following represents the default value of MIMEFILTERS: <MIMEFILTERS> application/mac-binhex40:m2h_external'filter:mhexternal.pl application/octet-stream:m2h_external'filter:mhexternal.pl application/oda:m2h_external'filter:mhexternal.pl application/pdf:m2h_external'filter:mhexternal.pl application/postscript:m2h_external'filter:mhexternal.pl application/rtf:m2h_external'filter:mhexternal.pl application/x-bcpio:m2h_external'filter:mhexternal.pl application/x-cpio:m2h_external'filter:mhexternal.pl application/x-csh:m2h_external'filter:mhexternal.pl application/x-dvi:m2h_external'filter:mhexternal.pl application/x-gtar:m2h_external'filter:mhexternal.pl application/x-hdf:m2h_external'filter:mhexternal.pl application/x-latex:m2h_external'filter:mhexternal.pl application/x-mif:m2h_external'filter:mhexternal.pl application/x-netcdf:m2h_external'filter:mhexternal.pl application/x-patch:m2h_text_plain'filter:mhtxtplain.pl application/x-sh:m2h_external'filter:mhexternal.pl application/x-shar:m2h_external'filter:mhexternal.pl application/x-sv4cpio:m2h_external'filter:mhexternal.pl application/x-sv4crc:m2h_external'filter:mhexternal.pl application/x-tar:m2h_external'filter:mhexternal.pl application/x-tcl:m2h_external'filter:mhexternal.pl application/x-tex:m2h_external'filter:mhexternal.pl application/x-texinfo:m2h_external'filter:mhexternal.pl application/x-troff-man:m2h_external'filter:mhexternal.pl application/x-troff-me:m2h_external'filter:mhexternal.pl application/x-troff-ms:m2h_external'filter:mhexternal.pl application/x-troff:m2h_external'filter:mhexternal.pl application/x-ustar:m2h_external'filter:mhexternal.pl application/x-wais-source:m2h_external'filter:mhexternal.pl application/zip:m2h_external'filter:mhexternal.pl audio/basic:m2h_external'filter:mhexternal.pl audio/x-aiff:m2h_external'filter:mhexternal.pl audio/x-wav:m2h_external'filter:mhexternal.pl image/gif:m2h_external'filter:mhexternal.pl image/ief:m2h_external'filter:mhexternal.pl image/jpeg:m2h_external'filter:mhexternal.pl image/tiff:m2h_external'filter:mhexternal.pl image/x-bmp:m2h_external'filter:mhexternal.pl image/x-cmu-raster:m2h_external'filter:mhexternal.pl image/x-pbm:m2h_external'filter:mhexternal.pl image/x-pcx:m2h_external'filter:mhexternal.pl image/x-pgm:m2h_external'filter:mhexternal.pl image/x-pict:m2h_external'filter:mhexternal.pl image/x-pnm:m2h_external'filter:mhexternal.pl image/x-portable-anymap:m2h_external'filter:mhexternal.pl image/x-portable-bitmap:m2h_external'filter:mhexternal.pl image/x-portable-graymap:m2h_external'filter:mhexternal.pl image/x-portable-pixmap:m2h_external'filter:mhexternal.pl image/x-ppm:m2h_external'filter:mhexternal.pl image/x-rgb:m2h_external'filter:mhexternal.pl image/x-xbitmap:m2h_external'filter:mhexternal.pl image/x-xbm:m2h_external'filter:mhexternal.pl image/x-xpixmap:m2h_external'filter:mhexternal.pl image/x-xpm:m2h_external'filter:mhexternal.pl image/x-xwd:m2h_external'filter:mhexternal.pl image/x-xwindowdump:m2h_external'filter:mhexternal.pl message/partial:m2h_text_plain'filter:mhtxtplain.pl text/html:m2h_text_html'filter:mhtxthtml.pl text/plain:m2h_text_plain'filter:mhtxtplain.pl text/richtext:m2h_text_plain'filter:mhtxtplain.pl text/setext:m2h_text_setext'filter:mhtxtsetext.pl text/tab-separated-values:m2h_text_plain'filter:mhtxtplain.pl text/x-html:m2h_text_html'filter:mhtxthtml.pl text/x-setext:m2h_text_setext'filter:mhtxtsetext.pl video/mpeg:m2h_external'filter:mhexternal.pl video/quicktime:m2h_external'filter:mhexternal.pl video/x-msvideo:m2h_external'filter:mhexternal.pl video/x-sgi-movie:m2h_external'filter:mhexternal.pl </MIMEFILTERS> MIMEARGS The MIMEARGS resource may be used to pass optional arguments to filters to control their behavior. Arguments may be defined on a per content-type basis, or for a specific filter itself. The syntax for each line of the the MIMEARGS element is as follows: <content-type>:<argument-string> Or, <filter-name>:<argument-string> The format of argument strings is dependent on the filter that processes <content-type> or by the specified filter, <filter-name>. If an argument string is defined for a filter explicitly and for a content-type that the filter processes, the content-type string will override the filter string. Examples The following example represents the default settings used by MHonArc: <MIMEARGS> image/gif:inline image/x-xbitmap:inline image/x-xbm:inline </MIMEARGS> The following example tells the filter that deals handles content-types that cannot be converted directly into HTML to use the "name" attribute as defined in the Content-Type header field as the name of the file generated: <MIMARGS> m2h_external'filter:usename </MIMEARGS> The following examples says to inline XBM images and use the name attribute as the filename if defined: <MIMEARGS> image/x-xbm:inline usename </MIMEARGS> _________________________________________________________________ _________________________________________________________________ GORY DETAILS This sections explain in detail how MHonArc functions. Knowing the material covered in this section may help you when trouble shooting. _________________________________________________________________ OS Detection MHonArc will automatically detect which operating system it is running under. If the following list of conditions are true, MHonArc assumes it is running under MS-DOS: * The COMSPEC environment variable is defined. * The value of the COMSPEC environment variable is a legal MS-DOS pathname. * The value of the COMSPEC environment variable is an executable file. If any of the above conditions is false, MHonArc assumes it is running under Unix. NOTE The previous conditions are used since the conditions will exist if Perl has been installed on an MS-DOS machine. None of the above conditions exist when Perl is installed on a Unix system. _________________________________________________________________ Processing Steps This section describes the steps MHonArc performs when creating/editting an archive. Anytime messages are added or deleted or the index page layout is changed, MHonArc will perform the following steps. * Creates a lock file. This insures only one MHonArc process is updating the archive at any given moment. See Archive Integrity for more information. * Reads the database file. The name, and location, of the database file can be explicitly specified via the M2H_DBFILE and M2H_OUTDIR environment variables or the command-line options -dbfile and -outdir. Otherwise, the current working directory is used. NOTE: The database file must be in the same location as the archive since the M2H_OUTDIR variable and -outdir option also specify the location of the archive. The database file contains data to update any mail threads and the resource settings when MHonArc was last invoked. This allows new messages to contain the same formatting/resource specifications as existing messages in the archive without having to re-specify the resources each time new messages are added. Resources defined in the database file override the environment variables. NOTE: If no database file is found, MHonArc will create a new archive. * Read the MHonArc resource file, if specified. The resource file will override any settings contained in the database file. * Read the settings specified on the command-line. Command-line options override any settings in the database and/or resource file. * Update archive. * Rewrites the index pages to reflect the update. * Writes a new database file containing the new state of the archive and all (new) resource settings. Normally, knowing all the previous steps is unnecessary. However, it may be useful to be aware of them if unexpected behavior, or errors, occur. _________________________________________________________________ Archive Integrity MHonArc applies safeguards to try to insure that a mail archive does not get corrupted due to exceptional circumstances. MHonArc does the following to insure a mail archive does not get corrupted: * MHonArc creates a lock file, ".mhonarc.lck", when creating/updating an archive. The lock file insures that only one MHonArc process is modifying an archive at any given moment. The -locktries command-line option, or the M2H_LOCKTRIES environment variable, allows you to control how long a given MHonArc process will wait if an archive is currently locked. If MHonArc can not lock the archive after the specified number of tries, MHonArc will exit, unless the -force option is specified. * MHonArc will ignore the following signals once messages are actually being written to disk: SIGABRT, SIGHUP, SIGINT, SIGQUIT, SIGPIPE, SIGTERM. Possible archive corruption can still occur if a SIGKILL signal is received since SIGKILLs are uncatchable. A SIGKILL will also prevent MHonArc from deleting the lock file. _________________________________________________________________ File Formats DATABASE FILE The MHonArc database file is actual Perl code. MHonArc requires it like any other Perl library to load in the contents of the database. CAUTION You should never modify the database file by hand. Changing the file by hand could cause future incorrect/unpredictable behavior when processing the archive. INDEX AND MESSAGE FILES The indexes and message files are legal HTML documents. However, manual editting of the documents is discouraged. The documents contain special comment declarations. The comment declarations act as markers which allow MHonArc to correctly edit the documents when needed. The comment declarations look like the following:     ... DERIVED FILES Derived files are files that are generated by the MIME filters. These files are created when the data being processed in messages cannot be converted to HTML (eg. images, postscript, video, binaries). The format of these files depend on the content-type of the data. _________________________________________________________________ Notes * Here is the explicit order of decreasing precedence when setting resources/options: + command-line options (highest precedence) + resource file + database file + environment variables (lowest precedence) * Mail thread detection is dependent upon the mail messages containing the message id(s) of referenced messages. Most mailers reply function will automatically include the message id of the message being replied to. * All mail message being converted into HTML are stored in memory before they are written to disk. This can eat up much memory if many mail messages are being converted. If you are processing multiple mailboxes/folders and worried about memory, you can try the following: + Invoke MHonArc on each one separately using the -add option. + Or, invoke MHonArc with the -savemem option. * The database file, and the index pages, are completely rewritten evertime new messages are added. This may cause slight slow-downs when archives become very large. * When reading MH mail folders, mail message are assumed to have numeric filenames. * When sorting by date, MHonArc tries to use the date listed in the first Received field of the message. If no Received field exists, than the Date field is used. * No distinction is made, in the output, on which messages came from which mail folder if multiple mail folders are processed. * MHonArc can probably be modified to handle other types of mailers (which has been done since the original version only supported MH mail folders). The MSGSEP resource gives flexibility in processing Unix style mailbox files. _________________________________________________________________ _________________________________________________________________ DIAGNOSTICS Three types of messages exist in MHonArc: Informative messages, Warnings, and Errors. Informative messages give you the current status of MHonArc's execution. Warnings signify undesired conditions, but are not critical in MHonArc's exection. Errors signify critical conditions that inhibit MHonArc from finishing its task. Another set of messages exists that are generated from the Perl interpreter itself. MHonArc tries its best to catch any conditions that may cause Perl to abnormally abort, but conditions may arise where this is not possible. This section describes the various diagnostics MHonArc may produce and messages Perl may produce. _________________________________________________________________ Informative messages Informative messages may be suppressed via the -quiet command-line option. Only the more important Informative messages are listed here. COULD NOT PROCESS MESSAGE WITH GIVEN CONTENT-TYPE: ... MHonArc will output this statement in filtered mail messages for content-types it is unable to process. See Default Filters in MIME for content-types that MHonArc supports by default. See Writing Filters for adding new filters into MHonArc. This is the only Informative message that does not go to standard output, but into the actual filtered mail message. NO NEW MESSAGES No mail messages exist when performing an add operation to an archive. This can occur if an empty MH mail folder, or empty mailbox file, is passed to MHonArc. REQUIRING MIME FILTER LIBRARIES ... Indicates MHonArc is loading external libraries for filtering mail messages. MHonArc will output each library it loads. See MIME for more information of filter libraries. TRYING TO LOCK MAIL ARCHIVE ... The statement means that a lock file is in place for the archive you are trying to update. Normally, an existing lock file implies that another MHonArc process is currently using the archive, and other MHonArc processes will wait awhile to see if the archive will be unlocked. However, there are times when a lock file exists, but no MHonArc process is modifying the archive. This can occur if MHonArc is abnormally terminated. If you know that no other MHonArc process is editting the archive you are try to modify, then manually remove the lock file or use the -force option. See Archive Integrity for more information. _________________________________________________________________ Warnings Warning messages denote some undesired event occurred, but the event is not severe enough to cause program termination. WARNING: COULD NOT FIND DATE FOR MESSAGE MHonArc was unable to find a received/sent date for a mail message. With respect to other mail messages, a message with no received/sent date is first in chronological order. WARNING: DATABASE (<DBVERSION>) != PROGRAM (<PRGVERSION>) VERSION Indicates that the version of MHonArc updating an archive is different from the version of MHonArc that created the database file. Problems can arise if the database file changes in format from different version of MHonArc. See the release notes of the MHonArc distribution if changes in the databse format has effects on older archives. WARNING: UNABLE TO CREATE <OUTDIR>/<DBFILE> Indicates MHonArc was unable to create the database file <dbfile> for the mail archive created/modified in <outdir>. This message can occur if <outdir> permissions changed during MHonArc execution, the existing <dbfile> is read-only, or the file system is full. This message can be severe because no future add operations can be performed to the archive. WARNING: UNABLE TO OPEN FOOTER: <FOOTER> MHonArc was unable to open the footer file, <footer>, for inclusion into the index page. Make sure <footer> exists, and is readable by you. WARNING: UNABLE TO OPEN HEADER: <HEADER> MHonArc was unable to open the header file, <header>, for inclusion into the index page. Make sure <header> exists, and is readable by you. WARNING: UNABLE TO OPEN <FOLDER> MHonArc was unable to open the specified mail <folder> for reading. Make sure <folder> exists and is readable (and executable if a directory) by you. WARNING: UNABLE TO OPEN MESSAGE: <FOLDER>/<MESSAGE> MHonArc was unable to open the specified MH mail message <folder>/<message> for reading. Make sure <folder>/<message> exists and is readable by you. WARNING: UNABLE TO OPEN RESOURCE FILE: <FILE> MHonArc was unable to open the resource file, <file>, for reading. Make sure <file> exists, and is readable by you. WARNING: UNDEFINED TIME ZONE: "<TIMEZONE>" MHonArc has found an unrecognized timezone acronym, <timezone>, in a mail message. You can tell MHonArc about other timezone acronyms, and their hour offset to UTC, by using the TIMEZONES resource element of the Resource File. The timezone UTC (or GMT) is used for an undefined timezone acronym _________________________________________________________________ Errors Errors denote conditions that cause MHonArc to abort execution. Some error conditions may cause the MHonArc archive to become corrupted. If the error occurs when MHonArc is writing files, you may have to recreate the archive from the original messages. ERROR: DATABASE READ ERROR OF <DBFILE> An error occured when trying to read an archive's database. The error can occur if the database file is not readable or the file got corrupted. ERROR: UNABLE TO CREATE <FILE> MHonArc was unable to create <file>. This message can occur if the directory being written to is not writable, a read-only file with the same name exists, or the file system is full. ERROR: UNABLE TO CREATE <LOCKFILE> AFTER <#> TRIES The statement means that a lock file is in place for the archive you are trying to update. Sometimes a lock file exists, but no MHonArc process is modifying the archive. This can occur if MHonArc is abnormally terminated. If you know that no other MHonArc process is editting the archive you are try to modify, then manually remove the lock file or use the -force option. ERROR: UNABLE TO OPEN <FILE> MHonArc was unable to open <file> for reading. Make sure <file> exists, and is readable by you. ERROR: UNABLE TO REQUIRE NEWGETOPT.PL The newgetopt.pl library is needed for MHonArc to parse the command-line. newgetopt.pl is part of the standard Perl distribution. Make sure Perl has been correctly installed at your site. ERROR: UNABLE TO REQUIRE TIMELOCAL.PL The timelocal.pl library is needed for MHonArc to process dates in messages. timelocal.pl is part of the standard Perl distribution. Make sure Perl has been correctly installed at your site. ERROR: UNABLE TO REQUIRE <FILE> This message signifies MHonArc was unable to require the library <file>. Make sure you properly installed MHonArc via the installation program. If <file> is your own custom filter, make sure you properly registered it in the Resource File. See also Specifying Filters and the PERLINC resource element. _________________________________________________________________ Perl Messages Generally, if execution is aborted and the following error messages appear, then you will have to manually delete the lock file since MHonArc will not have the chance to delete the file. CAN'T LOCATE <FILE> IN @INC AT <FILE> LINE <NUMBER>. A library that MHonArc tried to load was not found in the Perl include search paths. This error usually implies that MHonArc was not installed correctly. Make sure that MHonArc was installed via the install.me program that is provided in the MHonArc distribution. <FILE> DID NOT RETURN A TRUE VALUE AT <FILE> LINE <NUMBER>. If you are using your own MIME filters with MHonArc, make sure the library files return 1. _________________________________________________________________ _________________________________________________________________ GLOSSARY HTML Hypertext Markup Language. HTML is the main document markup language for the World Wide Web. MIME Multipurpose Internet Mail Extensions. MIME allows the transmission of non-ASCII data, and mixed content data, in electronic mail messages. MH Message Handler. MH is a free message handling system initially developed by the RAND Corporation, with subsequent development done at the University of Califonia: Irvine. Perl Practical Extraction and Report Language. Perl is an interpreted programming language suited for processing text and generating reports. SGML Standard Generalized Markup Language. SGML is a language for document representation. _________________________________________________________________ _________________________________________________________________ CONTACTS _________________________________________________________________ Mailing List A mailing list, mhonarc@rosat.mpe-garching.mpg.de, is available to provide a discussion forum on the usage and development of MHonArc. Appropriate topics for the list include: usage questions, bug reports, behavioral enhancements, documentation bugs, and general help. To subscribe to the mailing list, send mail to mhonarc-request@rosat.mpe-garching.mpg.de with the command, subscribe as the message body. If you send mail mhonarc@rosat.mpe-garching.mpg.de, your message will be distributed to all subscribers on the list. The mailing list is archived by Majordomo. You can also use the WWW to access the archive (with full text search using glimpse) at <URL:http://www.rosat.mpe-garching.mpg.de/mailing-lists/mhonarc/> _________________________________________________________________ People Earl Hood ehood@convex.com Main developer of MHonArc. Contact for bug reports, behavioral enhancements, documentation bugs, and Unix usage issues. Steve Pacenka sp17@cornell.edu Contributing developer. Worked on isolating code that would conflict with MS-DOS. Contact for MS-DOS installation problems or MS-DOS usage issues. Achim Bohnet ach@rosat.mpe-garching.mpg.de Contributing developer. Administrator, and maintainer, of the MHonArc mailing list. _________________________________________________________________